home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1994 March / Internet Info CD-ROM (Walnut Creek) (March 1994).iso / inet / ien / ien-108 < prev    next >
Text File  |  1988-12-01  |  15KB  |  552 lines
  1.  
  2. Internet Experiment Note 108
  3.  
  4.  
  5.  
  6.                       Internet User Queues
  7.  
  8.  
  9.  
  10.                        William W. Plummer
  11.  
  12.  
  13.                   Bolt Beranek and Newman, Inc.
  14.                         50 Moulton Street
  15.                       Cambridge MA   02138
  16.  
  17.  
  18.                           19 June 1979
  19.  
  20.  
  21.  
  22.  
  23.                       Internet User Queues
  24. William W. Plummer                                   19 June 1979
  25.  
  26.  
  27. The Internet JSYSes provide a facility for user programs to  send
  28. and  receive  Internet packets.  This set of calls is parallel to
  29. the "IMP special queue" calls, which dealt only with the ARPANET.
  30.  
  31. In order to use the Internet calls a program must first assign an
  32. Internet Queue using ASNIQ (JSYS 756).  The  arguments  for  this
  33. JSYS  are  a  set  of  mask  and  value words that determine what
  34. messages may be sent and which of the incoming messages  will  be
  35. delivered  to  the owning job.  A successful ASNIQ returns with a
  36. handle (a small number, short-hand for the queue),  in  T1  which
  37. can  then  be  fed  to  SNDIN  and  RCVIN (SeND InterNet, ReCeiVe
  38. InterNet).
  39.  
  40. The arguments for SNDIN  are  an  Internet  Queue  Handle  and  a
  41. pointer  to  a  buffer  of data in the caller's space.  Word-0 of
  42. this buffer is the size of the buffer, including this count word.
  43. Words 1 through 5 must have a Version 4 Internet Header (see last
  44. page).  Various fields of the header are  checked  for  legality,
  45. the  source  host word is filled in, the Internet header checksum
  46. inserted.  Then a network  interface  is  selected  and  a  local
  47. leader for that network is constructed in the packet.  The packet
  48. is then queued for output on that interface and SNDIN returns.
  49.  
  50. Basically, users have no control over which interface is selected
  51. for packet output and no knowledge of which interface an incoming
  52. packet  arrived on.  This is analogous to the ARPANET where users
  53. have no control over which IMPs a message actually goes  through.
  54. There  is  an  exception  when  a  system is equipped with a "Raw
  55. Packet Interface" (RPI) which is used  to  connect  to  a  remote
  56. gateway  or  a encryption device (such as a BCR).  Bit zero in T1
  57. to ASNIQ will flag the queue as using the  RPI  rather  than  the
  58. normal interfaces.
  59.  
  60. RCVIN  takes  the  same arguments, an Internet Queue Handle and a
  61. buffer pointer.  Normally, if no messages are already waiting  on
  62. the  queue, RCVIN waits.  This wait can be defeated by turning on
  63. the "don't wait" control bit which forces an error return  if  no
  64. messages  are  waiting.   When  a  message  is  available,  it is
  65. delivered to the user- supplied  buffer.   The  number  of  words
  66. filled  is  set  into the left half of word-0 (the count word) of
  67. the buffer.  Ordinarily this can be ignored, but if  the  message
  68. was  too big for the buffer, this tells how much space would have
  69. been required.
  70.  
  71. When finished, the queue handle can be released by  using  RELIQ.
  72. All  handles  owned by the job may be released by supplying -1 as
  73. the argument.
  74.  
  75.  
  76.  
  77.                               - 1 -
  78.  
  79.  
  80.  
  81.  
  82.                       Internet User Queues
  83. William W. Plummer                                   19 June 1979
  84.  
  85.  
  86. All Internet JSYS calls use only the left 32 bits of  each  word.
  87. This  is  true  of  both  the  ASNIQ  argument  block and of data
  88. buffers.
  89.  
  90.  
  91. Messages  left  waiting  on  an  input  queue  for  a  long  time
  92. (currently  30  seconds)  will  be deleted.  Also, a queue cannot
  93. hold very many messages (32, today).  Flooding an Internet  input
  94. queue to a slow receiver will result in dropped messages.
  95.  
  96. Messages  addressed  to  the  sending  host  will  ordinarily  be
  97. delivered without  sending  over  any  network  at  all  and  are
  98. reasonably fast.
  99.  
  100. User  programs have no control over which network a given message
  101. will be sent out over.  This decision will be made  by  the  host
  102. gateway module on the basis of routing information supplied to it
  103. by  other  Internet  gateways.   This  means that all networks to
  104. which  a  host  is  connected  must  go  down   before   Internet
  105. communications  will  be completely stifled, and even then, forks
  106. within a job will  be  able  to  communicate  due  to  the  local
  107. delivery mechanism.
  108.  
  109. Programs  using Internet messages must be aware that messages are
  110. not necessarily delivered in the order in which they  were  sent,
  111. some  messages  may  be  dropped and others duplicated.  Some may
  112. traverse a broadcast network and be clobbered by  other  packets,
  113. lightning,  flaky  intermediate gateways, etc.  Thus, some higher
  114. level protocol is needed in most cases.  TCP is one example,  but
  115. there are others (the "Datagram Protocol", XNET, etc.).
  116.  
  117. If  a  particular  protocol  is implemented in the monitor (e.g.,
  118. TCP) and that protocol module is turned on, no messages  of  that
  119. protocol  type  will  be  passed  to  users  via Internet queues.
  120. Assigning a queue will still be possible,  but  no  traffic  will
  121. reach the user unless that protocol module is disabled.
  122.  
  123.  
  124. Not  all  Internet protocols have ports.  If you are implementing
  125. one which does not, be  sure  that  .IQPTM  in  the  ASNIQ  block
  126. contains  a  zero.  If the protocol uses ports, they are expected
  127. to be in the  first  two  16-bit  bytes  following  the  Internet
  128. header,  source  port  first  and  destination  port second.  The
  129. location of this word is found by  adding  the  contents  of  the
  130. Internet  data  offset field to the address of the zeroth word of
  131. the Internet header.
  132.  
  133.  
  134.  
  135.  
  136.                               - 2 -
  137.  
  138.  
  139.  
  140.  
  141.                       Internet User Queues
  142. William W. Plummer                                   19 June 1979
  143.  
  144.  
  145. An additional feature of the Internet Queue Mechanism is that  it
  146. (optionally)  provides  an  logical  host  capability.   That is,
  147. incoming messages can be demultiplexed on the basis  of  bits  in
  148. the  Internet  Destination  Host  field.   Exactly which bits are
  149. considered logical host specifier  bits  depends  on  the  naming
  150. conventions  in  force in the network (area) to which the host in
  151. question is connected.  For ARPANET hosts, the middle 8-bit  byte
  152. of  the 24-bit Internet Host is considered to be the logical host
  153. specifier.
  154.  
  155. ASNIQ takes a specification of what numbers are to be used in the
  156. logical host bits of the source address  for  packets  which  are
  157. sent  and received.  When a packet is sent, the logical host bits
  158. are obtained  from  the  user's  packet  and  combined  with  the
  159. Internet  Host  Identifier  for  the  host being used, the result
  160. being  inserted  into  the  Source  Host  field  of  the  packet.
  161. Incoming packets are accepted by the Internet Layer if they match
  162. the Internet Host Identifier (Name) when the logical host bits of
  163. the destination address have been set to zero.
  164.  
  165. It  is  illegal to assign an Internet Queue such that the Logical
  166. host mask includes any bits which are not  part  of  the  logical
  167. host field.  ASNIQ will give an error return in this case.
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                               - 3 -
  196.  
  197.  
  198.  
  199.  
  200.                       Internet User Queues
  201. William W. Plummer                                   19 June 1979
  202.  
  203.  
  204. Assign Internet Queue JSYS
  205.  
  206. ;T1/    Pointer to queue descriptor block
  207. ;       (Bit-0: use Raw Packet Interface)
  208. ;T2/    (Unused, must be 0)
  209. ;T3/    (Unused, must be 0)
  210. ;
  211. ;       ASNIQ           (JSYS 756)
  212. ;Ret+1:  Failed.  Error code in T1.
  213. ;Ret+2: Success.  Internet queue handle in T1.
  214.  
  215. Format of a queue descriptor block:
  216.  
  217.         Word offset     Name    Contents
  218.  
  219.              0          .IQPRV  Internet protocol number in
  220.                                 bit 24-31.  Others should be 0.
  221.  
  222.              1          .IQFHV  Internet foreign host value word in
  223.                                 bits 0-31.
  224.  
  225.              2          .IQSHV  Internet source host value word in
  226.                                 bits 0-31.  Used for logical host selection.
  227.  
  228.              3          .IQPTV  Internet port value word.  Local port
  229.                                 value in bits 0-15, foreign port in 16-31.
  230.  
  231.              4          .IQPRM  Mask word corresponding to .IQPRV.
  232.  
  233.              5          .IQFHM  Mask word corresponding to .IQFHV
  234.  
  235.              6          .IQSHM  Mask word corresponding to .IQSHV
  236.  
  237.              7          .IQPTM  Mask word corresponding to .IQPTV
  238.                                 (Use 0 for portless protocols)
  239.  
  240. The  mask  words specify those bit positions where an exact match
  241. is required.  Thus, one can make  .IQFHM  contain 0 in  order  to
  242. talk  to  all Internet hosts.  Or by making say the low 3 bits of
  243. the local port mask word be 0, one owns eight ports.   Note  that
  244. an error will result unless the current QDB differs in the masked
  245. in  bits from all other Internet queues which are assigned at the
  246. instant the ASNIQ is issued.
  247.  
  248. Possible errors:
  249.  
  250. 600737,NTWZX1,NET WIZARD capability  required
  251. 600740,ASNSX1,All Internet queues in use
  252.  
  253.  
  254.                               - 4 -
  255.  
  256.  
  257.  
  258.  
  259.                       Internet User Queues
  260. William W. Plummer                                   19 June 1979
  261.  
  262.  
  263. 600741,ASNSX2,Conflict with some other job (# in AC2)
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.                               - 5 -
  314.  
  315.  
  316.  
  317.  
  318.                       Internet User Queues
  319. William W. Plummer                                   19 June 1979
  320.  
  321.  
  322. Release Internet Queue JSYS
  323.  
  324. ;T1/    An Internet Queue Handle or -1 for all
  325. ;T2/    (Not used.  Must be 0)
  326. ;T3/    (Not used.  Must be 0)
  327. ;
  328. ;       RELIQ   (JSYS 757)
  329. ;Ret+1:  Failure.  Error code in T1.
  330. ;Ret+2: Success.
  331.  
  332. This JSYS releases ownership of an Internet queue so  that  other
  333. jobs  can  assign  it.   Note that neither the RESET JSYS nor the
  334. EXEC RESET command execute RELIQs.   Thus,   once  the  queue  is
  335. assigned, it stays assigned until the job logs out.
  336.  
  337. Possible errors:
  338.  
  339. 600742,SQX1,Internet queue handle out of range
  340. 600743,SQX2,Internet queue not assigned
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.                               - 6 -
  373.  
  374.  
  375.  
  376.  
  377.                       Internet User Queues
  378. William W. Plummer                                   19 June 1979
  379.  
  380.  
  381. Send an Internet Message JSYS
  382.  
  383. ;T1/    Internet Queue Handle
  384. ;T2/    Pointer to buffer containing message
  385. ;T3/    (Not used. Must be 0.)
  386. ;
  387. ;       SNDIN   (JSYS 754)
  388. ;Ret+1:  Failure.  Error code in T1.
  389. ;Ret+2: Success.
  390.  
  391. The buffer must contain a word count in the right half of word-0,
  392. a  valid  Internet header in words 1 through 5, and possibly some
  393. data in words 6 and following.  If port filtering is  being  used
  394. (.IQPTM was non-zero for ASNIQ), the ports must be located in the
  395. word  following the Internet header.  The address of this word is
  396. found by adding the address of word-1 in the buffer to the number
  397. in the Internet data offset field.
  398.  
  399. The monitor fills in the source host field in the packet and also
  400. the Internet header checksum.  The rest of the header is what  is
  401. supplied by the user.
  402.  
  403. Possible errors:
  404.  
  405. 600742,SQX1,Internet queue handle out of range
  406. 600743,SQX2,Internet queue not assigned
  407. 600732,SNDIX1,Invalid message size
  408. 600733,SNDIX2,Insufficient system resources (No buffers available)
  409. 600735,SNDIX4,Invalid header value for this queue
  410.                 (Includes Internet Packet Length too big, Data offset
  411.                 too small, filtering on ports but packet length says
  412.                 packet does not contain a port word, and header does
  413.                 not fit the ASNIQ arguments).
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.                               - 7 -
  432.  
  433.  
  434.  
  435.  
  436.                       Internet User Queues
  437. William W. Plummer                                   19 June 1979
  438.  
  439.  
  440. Receive Internet Message JSYS
  441.  
  442.  
  443. ;T1/    Flags,,Internet Queue Handle
  444. ;               Bit-0: On to cause fail return instead of waiting
  445. ;T2/    Pointer to buffer where message will be put
  446. ;T3/    (Not used.  Must be 0.)
  447. ;
  448. ;       RCVIN   (JSYS 755)
  449. ;Ret+1:  Failure.  Error code in T1.
  450. ;Ret+2: Success.
  451.  
  452. Each RCVIN gets one message from the named queue.  These messages
  453. match the values in the queue descriptor block when masked by the
  454. mask  words  in  the  block.  The number of words filled plus one
  455. (counting the count word) is placed in the left half of word-0 of
  456. the buffer.  If the message was too  big  as  determined  by  the
  457. Internet  data length field, as much as will fit in the buffer is
  458. transferred and an error return given.  No  retry  for  the  same
  459. message is possible.
  460.  
  461. Possible errors:
  462.  
  463. 600742,SQX1,Internet queue handle out of range
  464. 600743,SQX2,Internet queue not assigned
  465. 600732,SNDIX1,Invalid message size
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.  
  489.  
  490.                               - 8 -
  491.  
  492.  
  493.  
  494.  
  495.                       Internet User Queues
  496. William W. Plummer                                   19 June 1979
  497.  
  498.  
  499. ; The following structure definitions have been excerpted from
  500. ; the file INPAR.MAC which is used in building TENEX and TOPS20
  501. ; monitors with Internet code.  Those who are unfamiliar with the
  502. ; structure facility should refer to SYS:MACSYM.MAC.  Basically,
  503. ; DEFSTR(Name,Location,Bit,Size)  defines a structure called Name.
  504. ; This field is held in the word (possibly an index) at Location.
  505. ; The right-hand bit number is Bit and the field is Size bits wide.
  506. ; A typical reference to the data offset field might be:   LOAD T1,PIDO,(PKT)
  507. ; where PKT is an index register which points at the zero-th word
  508. ; of the structure.
  509. ; Word offsets:
  510.  
  511.  .IPKVR==0              ; Word with version, type of service, etc
  512.  .IPKSG==1              ; Word with segmentation info
  513.  .IPKPR==2              ; Word with time to live, checksum, protocol
  514.  .IPKSH==3              ; Word with source host
  515.  .IPKDH==4              ; Word with destination host
  516.  
  517. DEFSTR(PIVER,.IPKVR,3,4)        ; PACKET.INTERNET.VERSION
  518. DEFSTR(PIDO,.IPKVR,7,4)         ; PACKET.INTERNET.DATA-OFFSET
  519. DEFSTR(PITOS,.IPKVR,15,8)       ; PACKET.INTERNET.TYPE-OF-SERVICE
  520.   ; Overlays for the above:
  521.   DEFSTR(PIPRI,.IPKVR,9,2)      ; PACKET.INTERNET.PRIORITY
  522.   DEFSTR(PISVD,.IPKVR,10,1)     ; PACKET.INTERNET.STREAM-VS-DATAGRAM
  523.   DEFSTR(PIREL,.IPKVR,12,2)     ; PACKET.INTERNET.RELIABILITY
  524.   DEFSTR(PISVR,.IPKVR,13,1)     ; PACKET.INTERNET.SPEED-VS-RELIABILITY
  525.   DEFSTR(PISPD,.IPKVR,15,2)     ; PACKET.INTERNET.SPEED-OF-DELIVERY
  526. DEFSTR(PIPL,.IPKVR,31,16)       ; PACKET.INTERNET.PACKET-LENGTH
  527. DEFSTR(PISID,.IPKSG,15,16)      ; PACKET.INTERNET.SEGMENT-ID
  528. DEFSTR(PIFLG,.IPKSG,18,3)       ; PACKET.INTERNET.FLAGS
  529.   ; Overlays for the above:
  530.   ; Unused bit
  531.   DEFSTR(PIDF,.IPKSG,17,1)      ; PACKET.INTERNET.DONT-FRAGMENT
  532.   DEFSTR(PIMF,.IPKSG,18,1)      ; PACKET.INTERNET.MULTIFRAGMENT
  533. DEFSTR(PIFO,.IPKSG,31,13)       ; PACKET.INTERNET.FRAGMENT-OFFSET
  534. DEFSTR(PITTL,.IPKPR,7,8)        ; PACKET.INTERNET.TIME-TO-LIVE
  535. DEFSTR(PIPRO,.IPKPR,15,8)       ; PACKET.INTERNET.PROTOCOL
  536. DEFSTR(PICKS,.IPKPR,31,16)      ; PACKET.INTERNET.HEADER-CHECKSUM
  537. DEFSTR(PISH,.IPKSH,31,32)       ; PACKET.INTERNET.SOURCE-HOST
  538.   ; Overlays for above:
  539.   DEFSTR(PISHN,.IPKSH,7,8)      ; PACKET.INTERNET.SOURCE.NET
  540.   DEFSTR(PISHT,.IPKSH,31,24)    ; PACKET.INTERNET.SOURCE.HOST
  541. DEFSTR(PIDH,.IPKDH,31,32)       ; PACKET.INTERNET.DESTINATION-HOST
  542.   ; Overlays for above:
  543.   DEFSTR(PIDHN,.IPKDH,7,8)      ; PACKET.INTERNET.DESTINATION.NET
  544.   DEFSTR(PIDHT,.IPKDH,31,24)    ; PACKET.INTERNET.DESTINATION.HOST
  545.  
  546.  
  547.  
  548.  
  549.                               - 9 -
  550.  
  551. -------
  552.